fix(spec): give every filter operator member a .describe() so the published filter reference documents all of them - #16432

Fixes #15059

content/docs/references/data/filter.mdx fills its Description column from prop.description — the JSON-Schema projection of a Zod .describe() (packages/spec/scripts/lib/schema-section.ts). A JSDoc block above a member never reaches that column. Every filter-operator member now carries a .describe(), so the published reference documents all of them instead of a subset.

Which path, and why

Path 1 — every operator member gets a .describe(). The card left the choice to this seat; the measurement made path 1 the cheap option rather than the expensive one.

Walking the live Zod graph (OS_EAGER_SCHEMAS=1, shapes read off the built schemas, not grepped) over the twelve schemas filter.zod.ts exports: 39 member slots, 20 described, 19 blank at the merge base. But those 19 do not need 19 new sentences. Seven of them are the page-facing blanks and need real prose; the other twelve are FieldOperatorsSchema restating operators whose prose already exists verbatim in the documentation copy. Hoisting that text into module constants and reading it from both copies covers those twelve mechanically.

So path 1 cost seven new descriptions plus a de-duplication — and a narrow pass would have re-created the very deferral this card exists to end (#14048 pushed exactly this sweep to "another card"; this is that card). After: 39 of 39 members described, 0 blank.

The duplicated names, all of them

The card warned that the same operator names appear more than once. They do — every one of the eighteen operator names is declared exactly twice, in the documentation copy and in the enforced FieldOperatorsSchema, and both sites are now described:

Rather than describing each pair twice, each description is now one module-level constant read by both sites — extending the pairing ORDERING_COMPARAND_DESCRIPTION and SET_MEMBER_DESCRIPTION already gave the ordering and set slots, whose own comment states the reason: the copies "share the CODE rather than a description of it, so they cannot drift". The remaining families now do the same, so an operator can no longer be documented in one copy and blank in the other.

$exists says the field HAS A VALUE

Its text is unchanged and still opens "Has-a-value check — the exact inverse of $null". $ne and $eq now say the same thing from their side ("{ "$ne": null } is the HAS-A-VALUE predicate ... it matches rows whose field holds a value, never rows that merely carry the key"), and the constant carries a comment saying a rewrite must keep saying "has a value". No key-presence wording is introduced anywhere.

The corpus ratchet reads identically

Both named rows unchanged before and after regeneration. The whole verdict block is byte-identical (diff of the two runs is empty):

BEFORE (merge base 0a038cc06d, before any edit)         AFTER (regenerated, final head 813450c8b5)
check-corpus-claim-drift: OK, no new claim sites        check-corpus-claim-drift: OK, no new claim sites
  Rules: 4 row(s) — exists-key-presence 4,                Rules: 4 row(s) — exists-key-presence 4,
         exists-portability 0, regex-retired 0,                  exists-portability 0, regex-retired 0,
         section-visiblewhen-unbound 0.                          section-visiblewhen-unbound 0.
  Scanned: 236 file(s), content/docs 190, skills 46.      Scanned: 236 file(s), content/docs 190, skills 46.

Both exit 0. The mechanism is structural rather than lucky: this gate excludes content/docs/references by path (SKIP_SUBTREES), because a finding in a generated tree names the wrong file — so the page this PR regenerates is not part of the scanned population at all. The .describe() text lands in exactly two places, packages/spec/json-schema/ (gitignored) and content/docs/references/data/filter.mdx; skills/** carries none of it.

Clause 2 — confirmed mechanically, not inherited

patch. No accept-set movement, no new export, no new key. Confirmed by running the gates rather than by reading the diff:

• pnpm --filter @objectstack/spec check:api-surface — exit 0
• pnpm --filter @objectstack/spec check:authorable-surface — exit 0
• pnpm --filter @objectstack/spec check:generated — exit 0 after regeneration; before it, its only stale artifact was content/docs/references/**, with api-surface/, authorable-surface/ + authorable-defaults/ + the .base.json anchor, export-origins/ and declaration-map/ all reported current on the same run. A rebuild of @objectstack/spec left git status clean apart from the page, so .describe() moved no committed projection of the schema graph.

gen:docs regenerated 228 files and modified one.

Counts, re-taken on this tree

Re-counted here rather than quoted, as the card instructs, each with a control that proves the search could return a hit.

The describe( figure drifts because two different things are being counted. At the merge base, grep -c 'describe(' answers 17 and grep -c '\.describe(' answers 16; the difference is one prose occurrence, a comment at :510 that spells the word describe() inside a sentence about $in / $nin, and is not a call site. Neither number is what the defect depends on. (At the final head: 49 and 35.)

The defect itself, with its control. At the merge base $eq carried the JSDoc /** Equal to (default) - SQL: = | MongoDB: $eq */ at :224, and on the generated page of the same commit:

grep -c 'Equal to (default)' content/docs/references/data/filter.mdx   -> 0     the JSDoc does not reach the page
grep -c '**$eq**'            content/docs/references/data/filter.mdx   -> 1     control: the row rendered, the pattern can hit

Blank Description cells on the page. The same regex over the same file, at the merge base and at the final head:

merge base -> 7   ($eq, $ne, where, $contains, $notContains, $startsWith, $endsWith)
final head -> 0

The 7 is the control for the 0: one pattern, one file, two commits.

One sub-claim of the card is not correct, and it is filed rather than fixed here

The card says FieldOperatorsSchema's restated $null / $exists leave "the FieldOperator table on the same generated page" blank. There is no FieldOperator table on that page. build-schemas.ts skips four of filter.zod.ts's exports outright, from its own output on this tree:

⊘ Data.ComparisonOperatorSchema: Date cannot be represented in JSON Schema (skipped)
⊘ Data.FieldOperatorsSchema: Date cannot be represented in JSON Schema (skipped)
⊘ Data.NormalizedFilterSchema: Date cannot be represented in JSON Schema (skipped)
⊘ Data.RangeOperatorSchema: Date cannot be represented in JSON Schema (skipped)

so grep -c 'FieldOperator' on the page returns 0 against a control of SpecialOperator returning 2. The card's core premise is unaffected and holds: JSDoc does not reach the page, .describe() does, and seven cells on a published page were blank.

A consequence of that skip is a real gap this PR deliberately does not touch — $gt / $gte / $lt / $lte / $between reach no published reference row at all, and the remedy is a generator or schema-shape change, which this card forbids. Filed as #16431. The members are described here anyway, so the two copies cannot drift.

Verification

dispatch-gates.mjs was re-derived after the changeset was written (85 commands before it, 91 after). Four gates first answered PREREQUISITE NOT MET because a package was unbuilt, not because of this diff; after building @objectstack/formula, @objectstack/lint, @objectstack/client-react and @objectstack/client all four pass: check:doc-formula-expressions, check:doc-security-posture, check:skill-examples, check:docs-transcript-drift.

Declared narrowing. pnpm check:dual-build-cjs-loads remains NOT MEASURED locally (exit 3, PREREQUISITE NOT MET): it reads every package's dist/, so it needs a full pnpm build, and it is left to CI. turbo ls --affected names 75 packages — every consumer of @objectstack/spec — so the affected-package test sweep is CI's run rather than this container's; no test anywhere asserts on these description strings (git grep for the existing description text across *.ts / *.mts / *.mjs returns only filter.zod.ts itself, against a control of FieldOperatorsSchema returning 10 files, test files among them).

Gate exits were captured before any pipe (cmd > log 2>&1; EXIT=$?), and the ratchet figures above are quoted from the gates' own verdict lines.

#15778 is not addressed here — same file, different pipeline, its own PR and changeset, exactly as triage ruled.

Generated by Claude Code